This document explains how to use FW_CListBox to implement list views in your part. FW_CListBox is a wrapper for Macintosh scrollable lists implemented by the List Manager, see Inside Macintosh “More Macintosh Toolbox”. It is well suited for simple 1 column list boxes. If your part requires lists or tables displaying non-string items, large amounts of data, or multiple columns, you need to implement them yourself.
The features and limitations of FW_CListBox in the current release are the following:
• 1 column only, with or without vertical scroll bar.
• A second invisible “client data” column lets you store 4 bytes values in each row.
• Items are strings up to 255 characters. Font can be changed but there is no custom drawing of other data.
• No more than 32K of total data (for instance, 1600 rows of 20 character strings).
• Single or multiple selection mode.
• Navigation and selection by keyboard.
• Auto-scrolling.
• The active list box can be outlined with a frame.
• Selecting an item with a double-click sends a notification to the list’s receivers.
• Extra work is required to display a list box across multiple facets or multiple frames (see Issues at the end).
ODF Form shows an example of a list box view. Run it and look at the source code in ODFDev:Form:Sources.
ODF Table is not an example of a multi-column list view, it displays a grid of cells where other parts can be embedded.
Adding a List Box to Your Frame
Creation by Program or by Resource
When creating a list box by program, use the 1-step initialization class constructor:
However it is easier to create the list box in resources, where the type FW_RListBox allows to initialize the strings at the same time. Form’s resource file views.fr contains the following:
The attributes used to create a list box are the following:
• A view id, required to be able to access this object later in your program.
• A bounds rectangle, placing the list box in its parent view.
• A binding flag. It should be initialized to FW_kFixedBounds in order to keep the list box in a fixed position when its parent is resized. You can change that by calling FW_CView::SetBindings or by using a different value in the resource.
• An initial number of rows (or items). You can change it later with AddStringItem or DeleteItems. Rows not initialized with a string will be displayed empty.
Note: do not use very large numbers! The list box is limited to 32K of data which is equivalent to 1600 rows of 20 characters strings.
• A vertical scroll bar flag. When true, or 1 in resources, the scroll bar is added during the list box creation, it cannot be added later. The scroll bar belongs to the list box view, i.e. it is not an ODF scroll bar object.
• A selection mode. When true, or 1 in resources, the list box is in single selection mode, the user can select only 1 item at a time. When false, or 0 in resources, the user can select several items simultaneously in various ways (see the section on Keyboard Navigation).
• A focus frame flag. When true, or 1 in resources, the list box is outlined by a frame when it has the keyboard focus. You should keep this flag on except in cases where the list box is the only view which can accept the keyboard focus in your frame.
Note: when the flag is true the list box rectangle is made smaller to leave space for the frame. The view bounds are not changed.
• A client data flag. When true, or 1 in resources, the list box is created with a second column made invisible. Using AddStringItem and SetStringItem you can store a 4 bytes “client data” value in this second column along with the string in the first column. This is useful if you don’t want to rely on the item’s index in the list when the user makes a selection. Instead of using the selected string or its index you can retrieve the client data value (which could be another index or a pointer) and perform the desired action. However if the list is not shuffled by adding and removing items, the selected item index is good enough in most cases.
• A double-click message. When not 0 the list box sends a FW_CListBoxNotification containing this message to its receiver objects to let them know which item has been double-clicked on. You can use the predefined value FW_kListBoxDoubleClickedMsg or your own.
• A font object. The class constructors use FW_kNormalFont by default which maps to Geneva 12 on Macintosh. In resource you can use a macro such as FW_NORMAL_FONT defined in FWViews.fr or define your own macro at the top of the .fr file, such as:
• A list of strings. In resources, you add a list of strings to initialize the list box, up to the number of rows declared above. Strings are added in the same order.
Handling Double-Click Notifications
FW_CListBox views are also notifiers, they can send notifications to other objects in response to a double-click on an item. If your frame, or another object, is interested in these events you must declare it after the views creation. It can be done in your CreateSubViews method, or your PostCreateViewFromStream method when using resources:
if (listBoxNotification.GetListBox(ev)->GetSelectedItem(ev) == 1)
FW_Beep();
}
break;
...
The cast of a notification object to FW_CListBoxNotification is safe because we know it’s a list box message. Once you get the list box object with GetListBox you can retrieve the selected item, check the list box id or take any other appropriate action.
See the Engineering note on Notifications for more information.
Responding to Single-Click Selections
FW_CListBox objects don't send notifications in response to single-clicks or when the selection changes. The mouse may be pressed on one item, moved and released on another one or released outside the list box. The selection may change by using the keyboard or by program instead of mouse clicks.
One way to detect mouse clicks is to implement a mouse click behavior as described later in this document. Your program can then find out if the selection has changed and take appropriate action. See FormView.cpp in the Form sample.
Tabbing Between List Boxes and Edit Views
List boxes and edit views can both receive the keyboard focus, i.e. become the frame’s target. You can implement a tabbing behavior by creating an FW_CViewTabber object. This cannot be done in resources in the current release, do it in your frame’s PostCreateViewFromStream method (or the CreateSubViews method if you are not using resources):
// ----- Add a ViewTabber event handler to the frame
fViewTabber = new FW_CViewTabber(ev, this);
You must not delete this object in the frame’s destructor, it will be done for you because this is an attached event handler.
A frame containing this event handler traps the Tab key and selects the next view that wants to be the target (or the previous one if the Shift key was pressed at the same time). The Tab key may be replaced by another key with the FW_CViewTabber::SetTabbingKey method. The current tab key is returned by GetTabbingKey.
Note: Dialog frames, instances derived from FW_CDialogFrame, have an FW_CViewTabber object already created for them.
Keyboard Navigation
A list box responds to Up and Down arrows, PageUp and PageDown, Home and End keys.
The following modifiers can be used to extend the selection in multi-selection mode:
• Shift-key: extends the selection continuously.
• Command-key: extends the selection discontinuously (with the mouse), or select the top item (Up arrow key), or select the bottom item (Down arrow key).
• Shift and Command keys together: select all items above (Up arrow key), or select all items below (Down arrow key)
FW_CListBox Reference
Warning: in ODF the index values for list box items are between 1 and N, where N = GetCountItems(ev), not between 0 and N - 1 like in the Macintosh List Manager API. Methods taking an index as an input argument will throw an assertion if you use an index that is out of range.
By default, the list box automatic drawing mode is on, all methods modifying the list box will update the screen if necessary. You can use the SetDrawingMode method to disable this behavior temporarily.
Getting/Setting selected items
virtual void SelectOneItem(Environment* ev, short index,
FW_Boolean selected = true);
If selected is true this method deselects any selected item and selects item number index. If selected is false, it deselects the item.
FW_Boolean GetSelectedState(Environment* ev, short index) const;
This method returns whether item number index is selected or not.
short GetSelectedItem(Environment* ev) const;
This method returns the index of the first selected item, or 0 it no item is selected. If the list box allows multiple selections you must use the GetSelectionCount and GetSelectedItems to retrieve all selected items.
short GetSelectionCount(Environment* ev) const;
This method returns the number of selected items, or 0 if no item is selected.
short GetSelectedItems(Environment* ev, short maxItems, short* indexArray) const;
This method can be used only in multiple selection mode. You pass maxItems, the number of items you want to get, and indexArray, an array of short integers of size maxItems. The method returns a short value, numItems, which is the actual number of selected items found, and fills the array with the indices of the selected items from 1 to numItems. If numItems is equal to maxItems there may be more selected items, use GetSelectionCount to get the exact number.
Adding/Changing/Deleting items
virtual void SetStringItem(Environment* ev, short index,
const FW_CString& str);
Use this method to replace the string of the existing item number index. The string must be less than 255 characters.
virtual void SetStringItem(Environment* ev, short index,
const FW_CString& str, void* clientData);
Use this method to replace the string the existing item number index and set its client data value at the same time (the list box must have been created with the Use Client Data attribute). The string must be less than 255 characters.
Use this method to add a new item to the list at position index, or at the end of the list if index is null. The string must be less than 255 characters.
Use this method to add a new item to the list at position index, or at the end of the list if index is null, and to set its client data value at the same time (the list box must have been created with the Use Client Data attribute). The string must be less than 255 characters.
virtual void DeleteItems(Environment* ev, short index, short count = 1);
This method removes count items from the list box, starting at position index.
Getting items
short GetCountItems(Environment* ev) const;
This method returns the number of items in the list box.
FW_Boolean GetStringItem(Environment* ev, short index, FW_CString& str) const;
This method returns the string stored at position index. Its returned value is false if this item was empty, true otherwise.
FW_Boolean GetStringItem(Environment* ev, short index, FW_CString& str,
void** clientData) const;
This method returns the string stored at position index in str and at the same time the clientData 4 bytes value (the list box must have been created with the Use Client Data attribute). Its returned value is false if there was no client data value associated with this item.
FW_Boolean GetClientDataItem(Environment* ev, short index,
void** clientData) const;
This method returns the clientData 4 bytes value of item number index (the list box must have been created with the Use Client Data attribute). Its returned value is false if there was no client data value associated with this item.
Utilities
FW_Boolean GetDrawingMode(Environment* ev) const;
This method returns true is the automatic drawing mode is on, false otherwise. The drawing mode must be on in order for the list box to be updated.
This method turns the automatic drawing mode on or off. You should turn it off only temporarily to avoid flashing during list box modifications. After you turn it back on you must force an update of the view with Invalidate().
This method returns the native Macintosh handle to the list record in case you need more internal information.
Warning: making direct List Manager calls may be dangerous.
Adding More Features to FW_CListBox
Mouse Click Behavior
You don’t necessarily need to subclass FW_CListBox to customize a mouse-click action. Using an event handler, or “behavior” object, allows you to do the same thing and avoids the need for a new resource type. For example the Form sample implements a CMouseUpBehavior class to check if 1 or more items have been selected and enable a button accordingly. See the file ODFDev:Form:Sources:FormView.cpp.
Content Model and Selections
If you decide to make a list box part of your content model you need to manage the presentation’s selection object as the user selects items and you need to externalize/internalize the list box data.
Miscellaneous Issues
Multiple Facets
When a list box view is visible in more than 1 facet you must force the redraw of all the other facets to see the correct update (i.e. the only facet updated by ODF is the active facet receiving keyboard events). In particular there will be drawing problems if the list box spans across facet boundaries!
Multiple Frames
The list box content is local to the frame because it is stored by in the platform’s list box record. If you open 2 frames of the same presentation, for example with the “View In Window” command, each frame contains its own list box and it is up to your part to maintain a common content when it makes sense to do so.
